前面十八章做了一件很重要的事：讓功能長出來。島上有任務、Gold、敵人、能力、商店與存檔。這些功能是用 Assistant 一章一章生成、拆解、測試、修正出來的。

但 AI 生成的專案常會有一個問題：每一段功能看起來都能跑，整個專案卻逐漸變得難維護。

這一章開始進入第五部「AI 生成後的工程整理」。本章不新增玩法，而是把前面長出的 Scripts、Modules、Remotes、Config 和 UI controllers 盤點一次，建立第一次可維護架構。

本章目標

完成本章後，你會得到：

• 一份目前 script 架構盤點方式。
• 一份 AI Adventure Island 目標架構。
• 一套讓 Assistant 先計畫、再小步重構的 prompt。
• Config、Remotes、Services、HUD Controllers 的整理策略。
• 一份每次整理後都要跑的回歸測試清單。

本章最重要的觀念是：

不要把「能跑」誤認為「可維護」。

AI 幫你快速生成功能，但你仍然要負責命名、位置、資料流、依賴關係和測試。

圖 19-1　可維護架構會分離資料存取、商業規則與網路介面，避免所有邏輯集中在單一 Script。

Context Pack

本章使用下列 Roblox 官方文件作為 context：

• Reuse code
• Script types and locations
• Services
• Explorer window
• Script Sync
• Build with a coding harness
• ModuleScript
• ServerScriptService
• ReplicatedStorage

本章採用這些文件中的幾個原則：

• script 的位置會影響它在 server 還是 client 執行。
• server logic 應放在 ServerScriptService。
• shared modules、config、RemoteEvent 可以放在 ReplicatedStorage。
• ReplicatedStorage 會複製給 client，因此不要放 server-only secret 或權威邏輯。
• ModuleScript 適合重用資料與函式，但要避免循環 require。
• Explorer folder 可以讓 DataModel 更容易掃描。

圖 19-2　Folder 用來表達責任與分類，不會自行改變執行行為；整理後仍要檢查 Script 路徑與 require 引用是否有效。

• Script Sync 可以支援長期維護與版本控制，但本章先以 Studio 內整理為主。

開場情境

目前專案可能長得像這樣：

ServerScriptService
├── CrystalCollectionService
├── GuideHintService
├── QuestService
├── EnemyAIService
├── AbilityService
├── ShopService
└── SaveService

ReplicatedStorage
├── Remotes
├── Inputs
├── QuestDefinitions
└── ShopConfig

StarterGui
└── AdventureHUD
    ├── AdventureHUDController
    ├── AbilityHUDController
    ├── ShopPanel
    ├── ObjectiveLabel
    ├── HintLabel
    ├── DashButton
    └── DashCooldownBar

這不是壞結構。它只是「一路做功能」自然產生的結構。問題是再做五章、十章後，它可能變成：

• config 有些在 ReplicatedStorage，有些寫死在 service 裡。
• RemoteEvent 有些在 Remotes folder，有些被 Assistant 放在其他地方。
• UI controller 有些重複監聽同一個 RemoteEvent。
• service 之間互相 require，資料流越來越不清楚。
• 修改一個名字後，另一端引用沒有同步改。
• 沒有一份回歸測試清單保證重構沒有破壞功能。

本章要做的是第一次停下來整理。這不是浪費時間，而是在專案變大之前降低後續成本。

第一個 Prompt

這章的第一個 prompt 不是叫 Assistant 直接修改，而是叫它盤點與提出計畫。

【Ch19 主任務｜整理可維護架構】
我們正在繼續製作 Roblox Studio 專案「AI Adventure Island」。

目前先不要修改任何內容。

請檢查目前的 DataModel，並提出一份架構整理計畫。

目前的功能背景：
- 水晶收集
- 包含 Crystals 與 Gold 的玩家 leaderstats
- QuestService 與 Guide 任務狀態
- EnemyAIService
- WindDash 能力與 AbilityService
- ShopService 與 ShopConfig
- SaveService 與 DataStore DEV store
- 包含任務、能力與商店 UI 的 AdventureHUD
- ReplicatedStorage.Remotes
- ReplicatedStorage.Inputs.PlayContext

請產出：
1. 目前的架構盤點：
   - Server scripts
   - ModuleScripts
   - RemoteEvents
   - InputAction objects
   - HUD LocalScripts
   - Config modules
2. 一份包含以下 folders 的目標架構：
   - ReplicatedStorage.Config
   - ReplicatedStorage.Remotes
   - ReplicatedStorage.Inputs
   - ServerScriptService.Services
   - StarterGui.AdventureHUD.Controllers
3. 一份目前不應搬移的 scripts 或 modules 清單，並說明原因。
4. 一份安全、可逐步執行的重構計畫。
5. 每一個步驟完成後要執行的回歸測試清單。

限制：
- 不要新增玩法功能。
- 不要改變玩法數值。
- 除非在同一個步驟同步更新 client 與 server 的引用，否則不要重新命名 RemoteEvents。
- 不要更改 DataStore store 名稱。
- 不要將 server-only logic 移到 ReplicatedStorage。
- 不要讓 ShopService 與 AbilityService 互相 require。

這個 prompt 的核心是第一句：

目前先不要修改任何內容。

當你要做架構整理時，Assistant 很容易直接動手。直接動手不是永遠錯，但重構的風險比新增一個孤立物件更高。先要求計畫，才能看到它是否理解目前專案。

Assistant 可能產生的結果

Assistant 可能會提出目前盤點：

Server scripts:
- CrystalCollectionService
- QuestService
- EnemyAIService
- AbilityService
- ShopService
- SaveService

Shared config/modules:
- QuestDefinitions
- ShopConfig

Remotes:
- RequestGuideHint
- QuestUpdate
- RequestAbility
- AbilityUpdate
- PurchaseUpgrade
- ShopUpdate

Inputs:
- PlayContext
- WindDash

HUD scripts:
- AdventureHUDController
- AbilityHUDController
- ShopHUDController or scripts inside ShopPanel

它也可能提出目標結構：

ReplicatedStorage
├── Config
│   ├── QuestConfig
│   ├── AbilityConfig
│   └── ShopConfig
├── Remotes
│   ├── RequestGuideHint
│   ├── QuestUpdate
│   ├── RequestAbility
│   ├── AbilityUpdate
│   ├── PurchaseUpgrade
│   └── ShopUpdate
└── Inputs
    └── PlayContext

ServerScriptService
├── Services
│   ├── CrystalCollectionService
│   ├── QuestService
│   ├── EnemyAIService
│   ├── AbilityService
│   ├── ShopService
│   └── SaveService
└── ServerMain

StarterGui
└── AdventureHUD
    ├── Controllers
    │   ├── QuestHUDController
    │   ├── AbilityHUDController
    │   └── ShopHUDController
    └── UI objects

這個目標結構的好處是每個區域的責任清楚：

• Config：資料定義。
• Remotes：client/server 通訊介面。
• Inputs：跨裝置輸入設定。
• Services：server-side gameplay logic。
• Controllers：client-side UI logic。

元件拆解

ServerScriptService

ServerScriptService 是 server-only script 的主要位置。它不會複製給 client，適合放：

• 存檔。
• 商店驗證。
• 任務狀態。
• 敵人 AI。
• 能力效果。
• 資源發放。

本章整理時，可以把 server scripts 放進 Services folder：

ServerScriptService
└── Services
    ├── QuestService
    ├── AbilityService
    └── SaveService

注意：把 Script 搬到 folder 後，路徑可能改變。如果其他 script 用 script.Parent.SomeModule 找東西，就可能壞掉。所以每次搬移都要檢查引用方式。

ReplicatedStorage

ReplicatedStorage 會複製給 server 與所有 client，因此適合放：

• RemoteEvent。
• InputAction / InputContext。
• shared config。
• server/client 都需要讀的 ModuleScript。

它不適合放：

• DataStore 存取邏輯。
• server 權威判斷。
• secret。
• 只應在 server 使用的安全邏輯。

例如 ShopConfig 放在 ReplicatedStorage.Config 是合理的，因為價格與描述可以給 UI 顯示；但 ShopService 必須留在 server。

ModuleScript

ModuleScript 適合整理重複資料與共用函式。

本章的整理可以把：

QuestDefinitions -> Config.QuestConfig
ShopConfig -> Config.ShopConfig
WindDash constants -> Config.AbilityConfig

但不要為了「看起來架構化」把所有東西都 module 化。Module 的價值在於：

• 消除有意義的重複。
• 讓資料有單一來源。
• 讓 service 的責任更清楚。
• 降低多處同步修改的風險。

如果某段 code 只有一個 service 使用，而且不複雜，留在 service 裡也可以。

Remotes

RemoteEvent 是 client/server 的合約。它們應該集中、命名清楚、方向明確。

目前可以整理成：

ReplicatedStorage.Remotes
├── RequestGuideHint       -- client -> server
├── QuestUpdate            -- server -> client
├── RequestAbility         -- client -> server
├── AbilityUpdate          -- server -> client
├── PurchaseUpgrade        -- client -> server
└── ShopUpdate             -- server -> client

不要把 RemoteEvent 藏在 UI、Tool 或某個 model 底下，除非你有非常明確的理由。集中放在 ReplicatedStorage.Remotes，讀者會更容易追資料流。

HUD Controllers

UI 也需要整理。StarterGui.AdventureHUD 可能已經包含任務、能力、商店等多個 controller。

可以整理成：

AdventureHUD
├── Controllers
│   ├── QuestHUDController
│   ├── AbilityHUDController
│   └── ShopHUDController
├── ObjectiveLabel
├── HintLabel
├── DashButton
├── DashCooldownBar
└── ShopPanel

重點不是把 UI 做漂亮，而是讓每個 controller 的責任清楚：

• QuestHUDController：處理 QuestUpdate。
• AbilityHUDController：處理 input 與 AbilityUpdate。
• ShopHUDController：處理 shop buttons 與 ShopUpdate。

不要讓三個 controller 都改同一個 label，除非有明確規則。

Regression Tests

重構後一定要跑回歸測試。這是本章最重要的工程習慣。

每搬一步都至少測：

1. Play Solo 無紅色 Output。
2. 水晶可收集，Crystals 增加。
3. Guide 任務可接、可完成、可給 Gold。
4. 敵人仍會巡邏、追蹤、扣血。
5. WindDash 可用，cooldown 正常。
6. 商店可購買升級，Gold 扣除。
7. SaveService 不報路徑錯誤。
8. HUD 仍收到 QuestUpdate / AbilityUpdate / ShopUpdate。

如果只在 Explorer 看起來很整齊，但回歸測試壞了，那不是成功重構。

Playtest

本章 Playtest 分成兩種：整理前測試與整理後測試。

整理前：

1. 記錄目前可以正常運作的功能。
2. 跑一次完整玩家流程。
3. 截圖或記錄 Explorer 中 scripts/remotes/config 的位置。
4. 記下 Output 中是否有既有 warning。

整理後：

1. 按 Play。
2. 檢查 Output 是否出現 Infinite yield possible、WaitForChild 找不到、attempt to index nil。
3. 跑水晶收集。
4. 跑 Guide 任務。
5. 跑敵人追蹤與傷害。
6. 跑 WindDash。
7. 跑商店購買。
8. 跑存檔流程或至少確認 SaveService 沒有路徑錯誤。

如果整理後出錯，優先懷疑「路徑」與「命名」：

WaitForChild("ShopConfig") 找不到
Remotes.PurchaseUpgrade 被搬了但引用沒改
AdventureHUDController 還在舊路徑找 DashButton

這些錯誤不代表架構方向錯，而是搬移步驟需要更小。

修正 Prompt

如果 Assistant 想一次重寫所有 script，使用：

【Ch19 修正 1｜不要一次重寫所有 scripts】
不要一次重寫所有 scripts。

我們正在整理架構，不是重寫玩法。

請將重構拆成以下小步驟：
1. 盤點目前的 scripts 與 remotes。
2. 只搬移 config modules。
3. 更新引用並測試。
4. 將 server scripts 移到 Services folder。
5. 更新引用並測試。
6. 將 HUD controllers 移到 Controllers folder。
7. 更新引用並測試。

除非有明確要求，否則不要改變玩法數值、DataStore 名稱或 RemoteEvent contracts。

如果搬 config 後找不到 module，使用：

【Ch19 修正 2｜修復 Config 引用路徑】
搬移 config modules 後，scripts 出現 WaitForChild 或 nil errors。

預期結果：
- QuestService、ShopService、AbilityService 應從 ReplicatedStorage.Config require config modules。
- Config module 名稱應為：
  - QuestConfig
  - AbilityConfig
  - ShopConfig

請只更新 require paths 與 WaitForChild paths。
不要更改 config values。

如果 RemoteEvent 搬移後 UI 失效，使用：

【Ch19 修正 3｜修復 RemoteEvent 路徑】
整理 remotes 後，HUD updates 不再運作。

預期結果：
- 所有 RemoteEvents 都位於 ReplicatedStorage.Remotes。
- Client 與 server 應使用相同的 paths。
- QuestUpdate、AbilityUpdate 與 ShopUpdate 仍應能傳到 HUD controllers。

請檢查 client 與 server 兩端的 RemoteEvent paths。
不要重新命名 RemoteEvents。

如果 service 互相 require，使用：

【Ch19 修正 4｜重構在 services 之間造成了循環依賴】
這次重構在 services 之間造成了循環依賴。

預期結果：
- ShopService 不應 require AbilityService。
- AbilityService 不應 require ShopService。
- SaveService 不應 require ShopService。
- 共用資料應透過玩家 attributes 或 config modules 傳遞，不要形成 service 彼此循環依賴。

請移除循環 requires，並維持清楚的 service boundaries。

如果整理後功能壞了但不知道哪裡壞，使用：

【Ch19 修正 5｜架構整理後，一個或多個玩法功能發生異常】
架構整理後，一個或多個玩法功能發生異常。

請使用以下回歸測試清單協助判斷問題：
- 水晶收集
- Guide 任務
- QuestUpdate HUD
- Enemy AI
- WindDash
- AbilityUpdate HUD
- 商店購買
- ShopUpdate HUD
- SaveService 載入／保存 paths

目前先不要重寫功能。
請先找出哪一項功能失敗、Output 中出現的第一個 error，以及涉及的 script path。

工程整理

本章完成後，不一定要真的把所有內容都搬完。對初學者來說，最重要的是學會整理方式：

先盤點
再計畫
一次搬一類
更新引用
立刻測試

推薦的第一輪整理順序：

1. 建立 ReplicatedStorage.Config。
2. 把 ShopConfig、QuestDefinitions、WindDash constants 整理進 config modules。
3. 確認所有 services require 新路徑。
4. 確認 ReplicatedStorage.Remotes 集中且命名一致。
5. 建立 ServerScriptService.Services，搬 server services。
6. 建立 AdventureHUD.Controllers，整理 HUD controllers。
7. 跑完整回歸測試。

整理後的目標結構：

ReplicatedStorage
├── Config
├── Remotes
└── Inputs

ServerScriptService
├── Services
└── ServerMain

StarterGui
└── AdventureHUD
    ├── Controllers
    └── UI objects

ServerMain 不是必須，但對較大的專案有幫助。它可以負責啟動各 service，讓 service 本身更像 module。不過本書目前仍可先保留各 service 作為 Script，避免一次引入太多架構。

本章總結

本章沒有新增玩家看得到的新功能，但它讓專案走向可維護。

你學到：

• script 位置會影響執行端。
• ServerScriptService 放 server-only logic。
• ReplicatedStorage 放 shared config、remotes、inputs。
• ModuleScript 適合整理資料與共用函式，但要避免循環 require。
• RemoteEvent 是 client/server 合約，搬移要同步更新兩端。
• UI controller 也需要責任分離。
• 重構一定要配回歸測試。

從這章開始，讀者要把 Assistant 當成會寫功能的協作者，也要把自己當成專案架構的負責人。

下一章會延續這個整理結果，專門處理安全問題：不要相信 client，也不要完全相信 AI 生成的程式。

關於 Wolke

嗨！我是 Wolke，曾任 Google Developer Expert（GDE，2019–2023） 與 LINE API Expert。

我熱衷於研究 AI Agent、n8n 自動化工作流與全端開發架構，致力於將 AI 技術轉化為真正能落地的生產力工具。

如果你喜歡這篇文章，歡迎透過以下方式與我交流：

📚 技術著作
《實用的 Gemini API 開發點子書》：帶你運用 Gemini App、Google AI Studio、Gemini CLI 與 Antigravity IDE，打造 AI Agent 與實用產品。

📝 技術部落格
歡迎追蹤我的 Medium，我會持續分享 Agentic Automation、架構設計與實際開發的踩坑心得。

🎤 技術講座與合作
我持續受邀至技術社群及研討會，分享 AI Agent、自動化工作流、DevOps 與全端開發實戰。

我曾於 DevOpsDays Taipei 2026 主講「不再只是寫腳本！讓 AI 代理人成為你的 SRE 最佳夥伴」工作坊。

如果你的企業、社群或學校正在尋找相關主題講者，歡迎私訊聯繫，洽談講座與工作坊合作！

🎮 我的 Roblox 遊戲

• ARCADE KINGS — Winning is just the beginning.
• 跑塔

🎁 免費贈送 OpenAI 或 Claude AI 額度

為了鼓勵大家實際動手打造自己的 Roblox 體驗，我每個月會開放：

• 10 個名額
• 每人 50 點 AI 額度
• 名額送完為止

參加方式：

1. 訂閱本系列文章。
2. 分享任一篇系列文章。
3. 私訊分享截圖及你的 AI 帳號 Email。

確認完成後，我會邀請你加入並設定 50 點額度。名額有限，歡迎把握機會！